Custom DialogsIntroduction to custom dialogsSmile supports custom dialogs. Custom dialogs can be opened by double-click them or, of course, by script.Smile enables you to create custom dialogs and also edit existing dialogs. Basically, this is accomplished by opening a blank dialog, configuring it with items from the Palette, and then adding your own scripting. The Palette is one of the "tools" shipped with Smile to better facilitate creating custom dialogs. The tools are actually a set of scripts shipped with Smile and are included in the "Dialogs" folder, somewhere in the "Advanced stuff" folder.The below writeups assume that the "Dialogs" folder has been placed in the "User scripts" folder, thus making these scripts (tools) available from the "Dialogs" submenu of the "Scripts" menu.Smile ships with two dialogs you will find helpful for the functions they provide, and they can serve as examples of what can be accomplished by using the custom dialog capabilities of Smile. These two dialogs are : "Find" dialog ("Edit" menu, "Find...") and the"Display selection length" dialog ("Scripts" menu ). These two examples are actually custom dialogs created by the Satimage team using the same tools that have been made available to you. Dialog tools at a glance ("Dialogs" submenu, of "Scripts" menu)• Align horizontally - aligns multiple selected items in horizontal • Align vertically - aligns multiple selected items in vertical • New dialog - opens a new, blank dialog • Palette- opens a Palette of items -- a source of items (buttons, and more) to create a custom dialog • Toggle dialog (shortcut Y)- toggles between "normal" and "edit" modes. See "Dialog mode" below. The general purpose "Duplicate" command (shortcut D) duplicates selected item with offset.Creating a custom dialog• New dialogChoose "New dialog" (Dialogs sub-menu of"Scripts" menu) to create an new, empty dialog. (Smile automatically opens new dialogs in the edit mode. See "Dialog mode" below.) Dialog windows can be moved, resized, and multiple windows can be open simultaneously. "New dialog" is not shipped with a shortcut key, but if you would like to assign one, see Keyboard shortcutsNote : in some cases, an existing custom dialog can be edited by dropping another item onto it. • Dialog mode ("normal" & "edit") (shortcut Y toggles)Dialog windows (or just "dialogs" for short) have two modes : "normal" and "edit". Use "normal" when actually using the dialog, and use "edit" when creating or editing the dialog. Smile automatically opens new dialog windows in the "edit" mode. "Toggle dialog" (shortcut Y) toggles the active (frontmost) dialog between "edit" and "normal" mode. Click of bottom right of dialog to verify mode : "Normal" mode : nothing happens. "Edit" mode : dialog border becomes dotted In addition to using the menu item or shortcut key, you can toggle the "mode" property by script. (For an example, see the "Toggle dialog/Y" script in the "Dialogs" folder.) • Palette (edit mode) Choose "Palette" (Dialogs sub-menu of"Script" menu) to open the Palette, which opens automatically in "edit" mode. The "Palette" includes items (such as buttons, list, popup, separator bar and fields) that can be dragged and dropped directly onto a dialog window to form a custom configuration. (Optionally, Palette items may be dragged to the Desktop to create "Clippings.") The function of each item of the Palette is generally evident from inspection ; however, don't miss the horizontal "separater line." It is also an item. Each item includes an index number (the lower-right corner), visible when the item is selected. The Palette serves as a convenient source of items to be dragged to create your custom dialog or to edit existing dialogs. When items are dragged from the Palette, they are copied , thus, the Palette itself remains unchanged. Each item of the Palette has an associated script, and the Palette itself also has an associated script. Smile ships with an empty script for each item of the Palette. See "Editing dialog script" below.Customizing a dialog • Resizing dialog ("edit" mode)Click and drag on the bottom-right corner of the dialog window to resize. Also note that each individual item (buttons, fields, separator bar, popup etc.) can also be resized. Any size changes are retained on saving the dialog. • Setting location ("edit" mode)Move the dialog to any location. The dialog will automatically re-open at this new location. • Adding a new item ("edit" mode)Use drag-and-drop or the clipboard to copy an item from the Palette to a dialog. Smile automatically secquences the item's index number as new items are added to the custom dialog. Items that have been made into clippings can be dragged to the dialog. Selected item(s) from one dialog may be dragged to another dialog. You can drag an item from the Palette to the Desktop to make a clipping. Such clippings can be then be copied by dragging onto a dialog. Additionally, items may be copied by dragging from one dialog to another if both are in edit mode. • Duplicating items ("edit" mode)If you have the "Duplicate" user script installed (see "Scripts" menu about installation of user scripts), use it to duplicate the selected items.• Deleting an item ("edit" mode) Click on the item to be deleted and drag it to the Trash, or use "Clear" (shortcut
) or "Cut" (shortcut X) of the "Edit" menu to delete a selected item(s). Note : "Undo" not implemented for delete function. And, "Delete" key does not delete the selected item of a dialog. • Saving an item ("edit" mode) You may want to save a particular item to disk, for instance to save its settings or its script for future use. Drag the item to the Desktop or to any folder of the Finder to make a clipping of dialog item.• Moving an item ("edit" mode) Use the mouse or keyboard on the selected item(s). The keyboard keys ( , , , ) move the selected item(s) by one pixel. (Select multiple items by clicking with Shift key depressed.) If the Shift key () is depressed, the arrows move the item(s) by 20 pixels. Black "tracks" may result on moving buttons and the horizontal separator bar on a dialog. These tracks can be useful to align items. To clear the black tracks, toggle from edit-to-normal-to-edit, or do window-shade up, window-shade down. • Cutting, Copying, Pasting items ("edit" mode) Use the "Edit" menu or associated shortcut keys. The "Cut" , "Copy" and "Paste" functions listed below apply to both the selected item(s) and its associated script. Cut - removes selected item(s) from dialog. Note : "Undo" is not implemented. Copy - copies selected item(s) to Clipboard Paste - pastes item(s) to dialog. Note : if any item of the dialog is selected, Paste will attempt to take place "in" the selected item. This makes sense only for item groups. If the selected item is not an item group, then pasting will have no effect. Note : when copying an item, an offset, 20 pixels (down and to the right) is applied to the copy stored in memory, so as to avoid possible confusion when pasting it in the same dialog. When pasting an item or a set of items, if a item group is selected, then the new items are created within this item group.Editing the items of a dialog ("edit" mode) Double-click any item to open a dialog box which contains fields and checkboxes. The dialog may differ depending on the item opened ; nevertheless, all possibilities are described below. • Name fieldEnter the item's name with the "Name" field selected. Use Tab key to switch field selection.• Contents field (not for all items)When item includes this field, enter contents with this field selected. Use Tab key to switch field selection. • "use script" checkboxIf checked, the script of the container of this item will be called when the user clicks the item. The container of the item can be the dialog, or another item (an item group). See below for more details on these calls. Note that clicking an item never automatically calls its own script.• "auto send" checkbox Only for dialogs attached to objects, see the advanced section.• Tag field Only for dialogs attached to objects, see the advanced section.• FontEnter a system font index (from -3 to 3), or a font name. The font index or font name is applied to the dialog item immediately after it is entered. Any system font name may be entered in the "Font" field. ("Geneva", "Helvetica" , etc. ) • Item script ("edit" mode) Each dialog item has an associated script, possible empty. To edit the script of a dialog item, Command-Option click ( click) it. Scripting a dialog • Editing dialog script ("normal" or "edit" mode)Use ( click) to open the dialog's script window. Click anywhere in body of the dialog (not title bar or in a dialog item). For general help on using script windows, see script windows. The script of a dialog is a particular case of an object script. • ScriptingTo script a dialog, you need to know what calls are made to the script of the dialog, and to the scripts of its items (if any), and when these calls occur. Then, you will write routines to handle these calls. Here are the calls :----------------------------on prepare theDialog -- in the dialog script set name of theDialog to "Hello world !" -- do whatever the dialog initialization requiresend prepare----------------------------"prepare theDlog" is sent to the dialog when the dialog is opened. The variable "theDlog" is a reference to the dialog. Use "prepare theDlog" exclusively to set the dialog's name. Note that the dialog's name -- the name appearing in the dialog's title window -- is not the file name. These names may differ. "prepare theItem" is sent to each dialog item when the parent dialog is opened. The variable "theItem" is a reference to the dialog item.----------------------------click in theDlogOrItem item number theIndex----------------------------This is sent to the container of a dialog item when the user clicks it, provided the dialog item has its "use script" setting checked (see "use script" checkbox above). The variable "theDlogOrItem" is a reference to the container of the dialog item, it can be the dialog itself or one of its items (an item group, in this case). "theIndex" is the index of the dialog item which received the click.This event is also sent to the dialog when the user makes a change in an editable text field of the dialog. ----------------------------idle theDlog----------------------------This event is sent to the dialog at idle time, provided its "want script" property is set to true (usually, this must be done by script). Dialog items do not automatically receive idle events.The value returned by the "idle" handler should be a real number. It is, in seconds, the time after which the "idle" handler will be called again.Of course, dialogs also receive usual events such as drop, do menu, delete, etc.Saving a dialog ("edit" mode)When in "edit" mode, "Save" ("File" menu) saves all modifications to file. The "Save" command only saves dialogs in "edit" mode.When done, save the dialog with the "Save" command of the "File" menu. Enter the file name and destination. Note that the dialog file name need not be the same as the dialog's title. The name in the dialog's title bar and is set through use of the dialog's script.Dialogs may be saved to any destination. Saving a dialog in the "User scripts" makes it openable by just selecting its name in the "Scripts" menu. For dialogs intended to be opened by script, not by direct selection by the user, a certain convenience will result if they are stored with the standard dialog files of Smile in the "More stuff" folder (pathname known by Smile as global variable "my gMoreStuffFolder"). Opening a dialog Like any regular document, dialogs can be opened by double-click, or by choosing "Open" in the "File" menu, or by a script. The dialogs which are in the "User Scripts" folder can be opened by selecting their name in the "Scripts" menu of Smile. • Opening dialog by script To open a dialog by script, use the following :----------------------------DisplayDlog("", theFile) -- general form ----------------------------where theFile = pathname of file containing dialog. If the script containing this line is not running from Smile, it must be encapsulated in a [tell application "Smile"] structure.For example, use the following script to open the "Display selection length" dialog stored in the "More stuff" folder.----------------------------DisplayDlog("", my gMoreStuffFolder & "Display selection dialog" ) ----------------------------For example, use the following script to open a dialog on the Desktop : ----------------------------DisplayDlog("", "1.2 HD:Desktop Folder:myFunDialog") -- specific example----------------------------========================================================Advanced• Customizing dialogs is advanced. Still more advanced is attaching a dialog to an object. This has to be done at the time when the dialog is created :----------------------------DisplayDlog(theObject, theFile)----------------------------where "theObject" is a reference to any Smile object, will attach the dialog created by the command to the object whose reference is stored in "theObject".• Once the dialog is attached to an object, you can link a dialog item (for instance, an editable text field) to a particular property of the object. This is what the dialog items named "tag" and "auto send" are designed for. In the "tag" field, specify the 4 characters code of the property you want to link the dialog item to. Then, check "auto send" to make the link active.========================================================
